The Metasys REST API is the exposed interface for accessing data from a Johnson Controls® Metasys system. This spec documents v5 of the API first released as part of Metasys 13.0. This documentation was last updated on June 25, 2024 at 2:12 PM (UTC).

Note
The Metasys REST API is only supported on the following Metasys products: ADS, ADX, and OAS. The REST API is not supported on Metasys for Validated Environments (MVE) sites. Do not attempt to use the REST API on an MVE site.

This version of the documentation includes INTERNAL operations which are only for use by approved Johnson Controls teams/projects.

This version of the documentation includes PRIVATE operations which are only to be used by Metasys developers for Metasys products. These operations should not be shared with other teams within Johnson Controls, nor should they be shared with third parties outside of Johnson Controls.

Metasys is a network-based building automation system (BAS) that operates the mechanical and electrical equipment in your building. For an introduction to Metasys, refer to Metasys System in Metasys System Configuration Guide. For a glossary of Metasys terms, refer to Metasys System Glossary. For additional information on Metasys, search the Johnson Controls documentation site Knowledge Exchange.

This specification defines the operations you can use to retrieve data through the API. For further information on the Metasys API, including tutorials, see the Metasys API home page.

© 2022 Johnson Controls Tyco IP Holdings LLP.

This documentation is for Metasys 13.0 which ships with version 5 of the Metasys Server.

The base path for the API is https://{hostname}/api/v5 where {hostname} is the host name of your Metasys server.

API Version Notes

Multiple versions of this API may be supported on one release of Metasys. At Metasys 13.0, the supported versions are v4 and v5. (However, v4 is deprecated and may be removed in a future release.)

Note: Versions earlier than v4 are not available on Metasys 13.0.

You must specify which version you intend to use in the URL, using the format v[#].

For example, https://localhost/api/v5/spaces for version 5 of spaces.

Documentation for v3 and earlier can be found here.

Version Response Behavior

The Content-Type header of the response will always contain (in part) the version of the API that was used to serve the request. This allows you to identify which version of the API was utilized.

For example, Content-Type: application/vnd.metasysapi.v5+json for version 5.

You must obtain an additional license to access some operations. For more information, refer to the Licensing information and Software information sections in Metasys System Software Purchase Options Product Bulletin (LIT-12011703).

Monitoring and Commanding API license

The Monitoring and Commanding API enables reading, writing, and commanding one or more Metasys objects/properties, including Present Value. This API succeeds the Metasys System Secure Data Access dynamic link library (MSSDA DLL).

The following operations require the Monitoring and Commanding API license:

• Get an object
• Edit an object
• Get attribute value
• List the commands of an object
• Send command
• Batch object operations

In general, you should assume that all URLs, parameter names, parameter values, payload property names and payload property values are case sensitive. For example:

• All attributes of objects are case sensitive. For example, many objects have an attribute named presentValue. It is case sensitive and must always be spelled presentValue.
• Enumeration set names and set members are case sensitive (for example, reliabilityEnumSet.reliable, displayPrecisionEnumSet.displayPrecision1, and writePriorityEnumSet.priorityDefault).

For operations where page and pageSize is allowed, the default page number will be 1 and is 1-based for all paths while the default pageSize will vary between paths. The page parameter indicates the page number of items to return from the path. The pageSize parameter indicates the maximum number of items in the response from the path.

Payloads returned by pagination-enabled paths have a similar structure. A total property indicates the total number of items included in all pages. A next and previous property supplies a link to the next and previous page of data, respectively. These properties can be empty if irrelevant (for example, if it is the first/last page, or there is only one page of data). The items property contains the data included in the page.

For operations where a sort query parameter is allowed, the supplied value should be in the format of a single attribute name, optionally prefixed with - to indicate descending sort order (ascending order is used if no prefix is supplied).

Payloads may contain links to related data, each represented as a property sharing the name of the respective relationship. The links point to either single or multiple related entities. A link to a single entity points to the canonical path for that entity. A link to multiple entities points to a path dedicated to representing that particular relationship.

For example, if object /objects/a has children /objects/b and /objects/c, the payload returned by /objects/a will have a property objects with a value of /objects/a/objects, because multiple children can be returned. However, the payload returned by /objects/b/ will contain a property parent with a value of /objects/a (not /objects/b/parent), because the relationship represents a single entity.

Additionally, each payload contain a self property, which contains a link representing the path used to obtain the data contained in the current payload.

All date-times in the alarms, audits, activities, and samples operations are ISO-8601 encoded strings in UTC. Other operations, such as objects, use a proprietary structure further described in supporting documentation.

There are some general rules that apply across all operations. If certain provided inputs are invalid or preconditions are not met, the API will respond with an appropriate error to indicate what went wrong.

The response payload of some operations in this document have a section of information labeled schema. This section of information includes important pieces of metadata about the item or items attributes that gives better context to the meaning of attribute values. This section follows JSON Schema specification with added custom annotation keywords.

This section describes the operations you can perform on activities. Activities are a superset of all alarms and audits in a Metasys system. Use activities operations to view audits and alarms. Apply filters to further refine the results.

Subscribe for activity-related events to receive updates when activities are created, discarded, acknowledged, or annotated.

Subscribing

To subscribe for activity-related events, complete the following steps:

1. Open a stream with the Get a stream operation. Take note of the stream ID.
2. Use Get Activities and include a METASYS-SUBSCRIBE header with the stream ID.

Note: Any filters added to the original GET operation also apply the event subscription.

Unsubscribing

To unsubscribe from an activities event subscription, complete the following steps:

1. Get the METASYS-SUBSCRIPTION-LOCATION from the subscribe operation response.
2. Issue a Delete activities subscription request to METASYS-SUBSCRIPTION-LOCATION.

See also:

• Get a stream
• Streaming
• Stream keep alive

Events

There are five event types sent by the activities subscription: acknowledged, annotate, discard, new, and heartbeat.

• activity.heartbeat - A heartbeat event is sent to show that the subscription is still alive. A heartbeat is a JSON string with the current UTC date time in ISO 8601 format and is sent every 30 seconds.

  Heartbeat Payload Example

  {
    "currentTime": "2021-02-16T16:21:10.23Z",
    "subscriptionIds": ["c569a157-7315-4f32-bc8f-11607f075660"]
  }
  

• activity.alarm.ack - An alarm acknowledge event is sent to indicate that the management status has changed to acknowledged.

  Acknowledged Alarm Payload Example

  {
    "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
    "activity": {
      "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
      "objectName": "OA_T",
      "activityManagementStatus": "acknowledged",
      "creationTime": "2021-02-16T20:30:00Z",
      "spaces": [
        {
          "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
          "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
          "name": "Floor 1",
          "spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
        }
      ],
      "equipment": [
        {
          "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
          "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
          "equipmentName": "Engine1",
          "shortName": null,
          "equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
        }
      ],
      "objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
      "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
      "alarm": {
        "message": "",
        "alarmGeneratorObject": {
          "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
          "referencedObject": {
            "objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
          }
        },
        "isAckRequired": true,
        "acknowledgedTime": "2021-02-16T20:31:02Z",
        "type": "alarmValueEnumSet.avHiAlarm",
        "priority": 70,
        "category": "objectCategoryEnumSet.generalCategory",
        "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
        "self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
        "triggerValue": {
          "item": "2.0",
          "schema": {
            "type": "string",
            "metasysType": "string",
            "units": {
              "id": "unitEnumSet.degF",
              "title": "deg F"
            }
          }
        },
        "description": ""
      }
    },
    "effectivePermission": {
      "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "canAcknowledge": true,
      "canDiscard": true,
      "canAnnotate": true
    }
  }
  

• activity.alarm.annotate - An alarm annotate event is sent when an annotation is added to an alarm activity, providing the information for the annotated alarm.

  Annotate Alarm Payload Example

  {
    "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
    "activity": {
      "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
      "objectName": "OA_T",
      "activityManagementStatus": "pending",
      "creationTime": "2021-02-16T20:30:00Z",
      "spaces": [
        {
          "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
          "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
          "name": "Floor 1",
          "spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
        }
      ],
      "equipment": [
        {
          "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
          "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
          "equipmentName": "Engine1",
          "shortName": null,
          "equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
        }
      ],
      "objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
      "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
      "alarm": {
        "message": "",
        "alarmGeneratorObject": {
          "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
          "referencedObject": {
            "objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
          }
        },
        "isAckRequired": true,
        "acknowledgedTime": "2021-02-16T20:31:02Z",
        "type": "alarmValueEnumSet.avHiAlarm",
        "priority": 70,
        "category": "objectCategoryEnumSet.generalCategory",
        "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
        "self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
        "triggerValue": {
          "item": "2.0",
          "schema": {
            "type": "string",
            "metasysType": "string",
            "units": {
              "id": "unitEnumSet.degF",
              "title": "deg F"
            }
          }
        },
        "description": ""
      }
    },
    "effectivePermission": {
      "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "canAcknowledge": true,
      "canDiscard": true,
      "canAnnotate": true
    }
  }
  

• activity.alarm.discard - An alarm discard event is sent when the management status of an alarm activity changes to discarded.

  Discard Alarm Payload Example

  {
    "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
    "activity": {
      "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
      "objectName": "OA_T",
      "activityManagementStatus": "discarded",
      "creationTime": "2021-02-16T20:30:00Z",
      "spaces": [
        {
          "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
          "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
          "name": "Floor 1",
          "spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
        }
      ],
      "equipment": [
        {
          "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
          "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
          "equipmentName": "Engine1",
          "shortName": null,
          "equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
        }
      ],
      "objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
      "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
      "alarm": {
        "message": "",
        "alarmGeneratorObject": {
          "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
          "referencedObject": {
            "objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
          }
        },
        "isAckRequired": true,
        "acknowledgedTime": "2021-02-16T20:31:02Z",
        "type": "alarmValueEnumSet.avHiAlarm",
        "priority": 70,
        "category": "objectCategoryEnumSet.generalCategory",
        "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
        "self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
        "triggerValue": {
          "item": "2.0",
          "schema": {
            "type": "string",
            "metasysType": "string",
            "units": {
              "id": "unitEnumSet.degF",
              "title": "deg F"
            }
          }
        },
        "description": ""
      }
    },
    "effectivePermission": {
      "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "canAcknowledge": true,
      "canDiscard": true,
      "canAnnotate": true
    }
  }
  

• activity.alarm.new - A new alarm event is sent when an alarm activity is created.

  New Alarm Payload Example

  {
    "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
    "activity": {
      "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
      "objectName": "OA_T",
      "activityManagementStatus": "pending",
      "creationTime": "2021-02-16T20:30:00Z",
      "spaces": [
        {
          "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
          "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
          "name": "Floor 1",
          "spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
        }
      ],
      "equipment": [
        {
          "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
          "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
          "equipmentName": "IDU1",
          "shortName": null,
          "equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
        }
      ],
      "objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
      "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
      "alarm": {
        "message": "",
        "alarmGeneratorObject": {
          "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
          "referencedObject": {
            "objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
          }
        },
        "isAckRequired": true,
        "type": "alarmValueEnumSet.avHiAlarm",
        "priority": 70,
        "category": "objectCategoryEnumSet.generalCategory",
        "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
        "self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
        "triggerValue": {
          "item": "2.0",
          "schema": {
            "type": "string",
            "metasysType": "string",
            "units": {
              "id": "unitEnumSet.degF",
              "title": "deg F"
            }
          }
        },
        "description": ""
      }
    },
    "effectivePermission": {
      "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "canAcknowledge": true,
      "canDiscard": true,
      "canAnnotate": true
    }
  }
  

• activity.audit.new - A new audit event is sent when an audit activity is created.

  New Audit Payload Example

  {
    "subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
    "activity": {
      "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
      "itemReference": "{hostname}:{deviceHostname}",
      "objectName": "MS-NAE5510-3",
      "activityManagementStatus": "pending",
      "creationTime": "2021-02-16T16:21:10.23Z",
      "objectUrl": "https://{hostname}/api/v5/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
      "objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
      "audit": {
        "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
        "status": null,
        "preData": null,
        "postData": {
          "item": "10.10.198.131",
          "schema": {
            "type": "string",
            "metasysType": "string"
          }
        },
        "parameters": [],
        "errorString": null,
        "user": "MetasysSysAgent",
        "signature": null,
        "classLevel": "auditClassesEnumSet.userActionAuditClass",
        "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
        "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
        "annotationsUrl": null,
        "self": "https://{hostname}/api/v5/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
      }
    },
    "effectivePermission": {
      "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
      "canDiscard": true
    }
  }
  

• activity.audit.annotate - An annotate audit event is sent when an annotation is added to an audit activity, providing the information for the annotated audit.

  Annotate Audit Payload Example

  {
    "subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
    "activity": {
      "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
      "itemReference": "{hostname}:{deviceHostname}",
      "objectName": "MS-NAE5510-3",
      "activityManagementStatus": "pending",
      "creationTime": "2021-02-16T16:21:10.23Z",
      "objectUrl": "https://{hostname}/api/v5/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
      "objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
      "audit": {
        "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
        "status": null,
        "preData": null,
        "postData": {
          "item": "10.10.198.131",
          "schema": {
            "type": "string",
            "metasysType": "string"
          }
        },
        "parameters": [],
        "errorString": null,
        "user": "MetasysSysAgent",
        "signature": null,
        "classLevel": "auditClassesEnumSet.userActionAuditClass",
        "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
        "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
        "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
        "self": "https://{hostname}/api/v5/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
      }
    },
    "effectivePermission": {
      "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
      "canDiscard": true
    }
  }
  

• activity.audit.discard - An audit discard event is sent when the management status of an audit activity changes to discarded.

  Discard Audit Payload Example

  {
    "subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
    "activity": {
      "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
      "itemReference": "{hostname}:{deviceHostname}",
      "objectName": "MS-NAE5510-3",
      "activityManagementStatus": "discarded",
      "creationTime": "2021-02-16T16:21:10.23Z",
      "objectUrl": "https://{hostname}/api/v5/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
      "objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
      "audit": {
        "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
        "status": null,
        "preData": null,
        "postData": {
          "item": "10.10.198.131",
          "schema": {
            "type": "string",
            "metasysType": "string"
          }
        },
        "parameters": [],
        "errorString": null,
        "user": "MetasysSysAgent",
        "signature": null,
        "classLevel": "auditClassesEnumSet.userActionAuditClass",
        "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
        "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
        "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
        "self": "https://{hostname}/api/v5/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
      }
    },
    "effectivePermission": {
      "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
      "canDiscard": true
    }
  }
  

Filter Behavior

Filters supplied to an activities request limit the results to activities for which the filters apply. When subscribing to an activities request that uses filters, the events received are also limited to the same filter criteria. Exceptions to this behavior occur when filtering on activity management status, such as for acknowledged or discarded activities. You receive an update whenever an activity management change occurs, regardless of filters, because the change can impact the original set of activities you subscribed to. For example, consider the following scenario:

• You subscribe to acknowledged activities and receive all acknowledged activities, receiving updates for any acknowledged thereafter across the stream.
• In this state, one of the activities in your original list is discarded by another user.

When this occurs, you receive an activity.alarm.discard message for the discarded activity even though your filters exclude activities that are discarded. This is necessary so that you can properly maintain the state of activities already received in your application.

The priority alarm is the newest, highest priority alarm that is pending required acknowledgement by the current user. A user can subscribe to receive the initial and all subsequent changes to the current priority alarm and total pending acknowledgement alarm count over streaming notifications.

Subscribing

To subscribe for priority alarm notifications, complete the following steps:

1. Open a stream with the Get a stream operation. Take note of the stream ID.
2. Use the Create priority alarm subscription operation using the stream ID in the URL.

Unsubscribing

To unsubscribe from a priority alarm subscription, complete the following steps:

1. Get the Location from the subscribe operation response.
2. Issue a Delete priority alarm subscription request to Location.

See also:

• Get a stream
• Streaming

Events

There are two event types sent by the priority alarm subscription:

• activities.priorityAlarm.heartbeat - A heartbeat event is sent to show that one or more subscriptions are still alive. A heartbeat is a JSON string with the current UTC date time in ISO 8601 format and is sent every 30 seconds.

• activities.priorityAlarm.update - An update event is sent when the current priority alarm changes and/or the total pending acknowledgement alarm count changes

Alarms alert users to potential problems identified by a Metasys system, for example high zone temperatures. Use alarms operations to get object alarms, network device alarms, single alarms, alarm collections, and alarm annotations. Acknowledge or discard alarms with the edit patch operation. Filter the results with the query parameters time, priority, type, category, acknowledgement, and page. Sort the results by creation time and priority.